Instructional Guide: 
End-User 
Documentation Kit 
for Palm OS°®5 


Welcome to the End-User Documentation Kit instructional guide. The 
information in this guide shows you how to build customized end- 
user documentation for a device that is based on Palm OS software. 


What is the End-User Documentation Kit? 


The End-User Documentation Kit is a set of files and instructions that 
lets you build a set of customized documentation for your device. 
The kit is provided on the Palm OS 5 Product Development Kit 
(PDK) CD and includes: 


e A master documentation set that includes front matter, a 
table of contents, and an index. It also includes individual 
chapters for standard operating procedures, Graffiti® 
writing, and each Palm OS basic application. For a 
description of the contents of each chapter, see“Contents of 
the End-User Documentation Kit” on page viii. 


The annotated template used to create the End-User 
Documentation Kit. This template gives tips on the how to 
best use the tags, and how to handle tables and graphics. 


An instructional file in PDF format (Instruct.pdf) that 
provides step-by-step instructions for building a set of 
customized documentation for your device (you are reading 
this file now). 
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Requirements 

To use the End-User Documentation Kit, you need: 
Adobe FrameMaker 6.0 
Adobe Acrobat Reader 4.0 to open the Instruct.pdf file 
Helvetica and Palatino fonts (Type 1 or TrueType) 


An intermediate to advanced knowledge of Adobe 
FrameMaker, including how to generate, update, and 
rearrange book files; how to define variables and cross- 
references; and how to create index markers. 


How does the End-User Documentation Kit 
work? 


The End-User Documentation Kit contains all the basic information 
you need to build documentation for your product. To customize 
the documentation for your device, you will need to supply specific 
information about your product, and you will need to read and edit 
the documentation as appropriate for your product. 


Within the individual chapters of this kit you will find variables, 
instructional notes, and suggestions to help you build your 
documentation. The following types of information is included in 
the chapters of the documentation kit: 


¢ Variables. Variables are placeholders you replace with 
information specific to your product. Variables are displayed 
in red so they can be easily identified within the body of the 
text. Once you have assigned definitions to the variables in 
one chapter, simply import the variable definitions into the 
remaining chapters you plan to use for your documentation. 


Template alerts. Template alerts are messages, displayed in 
blue, that you should consider as you create your 
documentation. Once you have read and considered the 
information in a template alert, delete the alert. 


Example: 


Template Alert! (Delete this alert when completed): This is a sample 
of a template alert. Once you’ve considered and acted on the infor- 
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mation in the alert, triple-click to select the entire paragraph, then 
press Backspace or Delete to delete it from the chapter. 


¢ Illustration suggestions. These are suggestions for adding 
an illustration to a step or section. In many cases, a sample 
illustration is provided for your reference; you must replace it 
with an illustration specific to your device. 


Example: 


Illustration suggestion (Delete this suggestion when completed): This is a sample of 
an illustration suggestion. Once you've considered and acted on the information in 
the suggestion, triple-click to select the entire paragraph, then press Backspace or 
Delete to remove it from the chapter. 


Before you begin 


Before you begin creating documentation for your product, review 
the conceptual overview provided in this instructional guide to 
identify the procedures for building documentation. Once you’ve 
reviewed this, you can begin building documentation using the 
step-by-step instructions in "Building documentation for your Palm 
OS device" on page x. To build documentation, these basic steps are 
required: 


¢ Make a copy of the master documentation files and place 
them on your hard drive. 


¢ Rename the book file to a name specific to your product. 
e Assign definitions to variables within the chapters. 


¢ Read and edit the documentation to customize it for your 
product. 


¢ Create cross-references as needed. 
¢ Create additional index entries, if desired. 


¢ Make any desired cosmetic changes, such as changing fonts 
or adjusting paragraph styles. 


¢ Generate a book file to compile your book and all the 
changes. 
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Contents of the End-User Documentation Kit 


The End-User Documentation Kit consists of several individual 
FrameMaker files related to Palm OS software operating procedures 
and applications. Depending on the requirements of your Palm OS 
device, you might use some or all of the chapters. The chapter 
names and a brief description of each is provided below. 


00Front.fm is the title page of your publication name and the 
copyright page. 

MasterTOC.fm contains the master table of contents, 
regenerated each time the book file is generated /updated. 


00About, Provides a brief introduction to this guide. 


01Intro.fm, Chapter 1, introduces your device, provides 
system requirements for desktop software (if applicable), and 
discusses basic elements of the user interface. In addition, 
information about opening applications, entering data, and 
using Graffiti writing is included. 


02Data.fm, Chapter 2, shows you how to enter data in four 
ways: with the stylus or the onscreen keyboard; and if 
applicable, with the computer keyboard, or by importing 
data from another application. 


03Manag.fm, Chapter 3, provides information about how to 
manage and categorize applications on your device, and how 
to add applications to your device. 


04Apps.fm, Chapter 4, is the introductory page to the 
applications chapter. Any application your device includes 
follows the information in this chapter and appears to be part 
of this chapter. Individual application filenames are 
preceded by an exclamation point (!) and automatically fall 
into place after the introductory information in this section. 


!Datebook.fm is the Date Book application chapter. 


!Address.fm is the Address application chapter. 


!Todolist.fm is the To Do List application chapter. 


!Memopad.fm is the Memo Pad application chapter 


!Calcu.fm is the Calculator application chapter. 


!Expense.fm is the Expense application chapter. 
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!WebClip.fm explains how to use web clipping to receive 
web content on your device. 


!SMS.fm explains how to send and retrieve Short Messaging 
Servicing (SMS) messages via a mobile phone. 


05Attention.fm, Chapter 5, describes the Attention Manager, 
and how you use it to manage all notifications in one place. 


06ExpCard.fm, Chapter 6, describes how to use an expansion 
card on your device. Tasks such as displaying contents, and 
beaming and deleting applications are discussed. 


07Phone.fm, Chapter 7, explains how to connect your device 
to a GSM mobile phone for wireless communication. 


08Tasks.fm, Chapter 8, describes tasks common to all basic 
Palm OS applications. Because your device might not use all 
the applications, you must read and edit this chapter to 
reference only the applications used by your device. 


09Mail.fm, Chapter 9, describes the Palm OS mail 
application. 


10Beam.fm, Chapter 10, describes how to beam information 
from one device to another, including the Short Message 
Servicing (SMS) feature. 


11HotSync.fm, Chapter 11, describes how 
HotSync® exchanges and updates information between your 
device and your computer’s desktop. 


12Connect.fm, Chapter 12, describes preferences options for 
your modem and network. 


13Maint.fm, Chapter 13, is created by you, the device 
manufacturer. Use this chapter to describe how to maintain 
the device, for example, when to change batteries, how to 
clean it, and so forth. As this is an optional chapter, you can 
delete it from the book file if desired. 


14faq.fm, Chapter 14, is created by you, the device 
manufacturer. Use this chapter for Frequently Asked 
Questions, troubleshooting, etc. This is an optional chapter; 
you can delete it from the book file if desired. 


MasterIX.fm is the master index chapter. Each time an index 
marker is added and the book file is generated /updated, the 
index is updated. As a general rule, update individual 

markers within the chapters of the book to correct the index; 
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if you correct the index file directly and then generate/ 
update the book file, any edits made previously are lost. 


Document statistics 


The Adobe FrameMaker files supplied with the End-User 
Documentation Kit have default document control values for page 
size, fonts, and so forth. You can change these default values for 
your documentation; however, be sure to import the settings into 
every chapter for consistency. The defaults are: 


Page Size: 8-1/2 inches by 11 inches. 


Smart Quotes and Smart Spaces options turned on in Text 
Options. 


Variables: Generic variables, which you change to make 
specific to your product. See "Step 5: Define variables" on 
page xiv for information about how to define variables. 


Cross-references: All cross-references are disabled and 
displayed in magenta text. Depending on your needs, either 
delete the cross-references or make them active. 


Styles: A definition of all the styles used in the End-User 
Documentation Kit is provided in the folder 
Template_Book_Annotated. You can change the styles if you 
want; however, be sure to use the File > Import > Formats 
command to update the style changes in all the files. 


Graphics: In many cases, screenshots are provided (copied 
into the documents) as samples. You must replace these 
samples with screenshots specific to your device, as they are 
samples only. 


Building documentation for your Palm OS device 


Once you’ve reviewed the introductory information and installed 
the necessary software, you are ready to begin building 
documentation for your product. There are eight basic steps 
required to create a documentation set. 
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Step 1: Make a copy of the master 
documentation files 


To begin the process of creating documentation for your device, copy the 
master documentation files onto your hard drive. 


After copying the master documentation onto your hard drive, 
rename the master book file to a name specific to your product. 
To create a set of master files for your device: 


1. Open the End User Docs folder on the Product Development 
Kit (PDK) CD and locate the Master Docs folder. 


2. Copy the Master Docs folder onto your hard drive. This 
folder contains all the files and graphics you need for your 
documentation. 


3. Rename the Master Docs folder to a name appropriate to 
your product. 


To rename the master book file: 


1. Open the folder you renamed in the previous step and locate 
the Master.book file. 


2. Rename the Master.book file with a name appropriate to 
your product. 


At this point, you open the renamed book file and begin editing the 
files to create a set of documentation for your product. 


NOTE: For purposes of this instructional guide, the newly 
named book file is referred to as Master2.book, but you may use 
any name you wish. 


Step 2: Verify the documentation files 

Before continuing, take a moment to open your new book file and 
verify that the chapters are accessible from the book file. 

To open the book file: 


1. Open your renamed book file. For instance, you might have 
renamed the book file Master2.book. 


The Master2.book file contains a list of references to all the files used 
to create a set of documentation. Note that the basic applications 
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chapters are preceded by an exclamation point (!) to differentiate 
them from other chapters. 


In addition, you'll notice that the table of contents (MasterTOC.fm) 
and index (MasterIX.fm) retain the same prefix as the original book 
file’s name. However, they will generate properly within your new 
book file, so there is no need to rename them. 


FR) C:\WINDOWS\D... Fel Ea 


Files in Book: 


MasterTOC.fm+ Table of contents file 


#Todolist.tm Basic application file names are 
preceded by an exclamation 


#Calcu.fm point(!) 


O5tasks.fm 
06Mail.fm 
07Beam.fm 
O8Query.fm 
O9HotSync.fm 
10modnet.fm 


MasterlX.fm+ Index file 


2. Double-click any file name within the list of files. (The 
urpose of this step is to familiarize you with the way the 
iles look onscreen.) 


TIP: Leave the book file open in FrameMaker to make all files 
easily accessible rather than having to choose File > Open each 
time you want to open a file. 


Step 3: Remove unused basic application files 


Next, edit the book file to remove the basic applications files that 
your device does not use. The basic application files are preceded by 
an exclamation point (!). 
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NOTE: If your device uses all the basic applications, skip this 
step. 


To delete unused files from the book file: 


1. Make sure the book file is open; then choose File > Rearrange 
Files. 


2. Highlight an application chapter (a chapter preceded by an 
exclamation point (!)) that you want to remove. 


3. Click Delete to remove the reference to the basic application 
chapter from the book file. 


4. Repeat steps 2 and 3 to remove any other unused basic 
application chapters. 


5. Click Done when you've deleted all the desired files. 
6. Choose File > Save to save the changes to the book file. 


7. When you delete a file name from the book file, you delete 
only a reference to the file, not the actual file. 


NOTE: If you delete a file mistakenly, close the book file without 
saving changes; then reopen it and use the File > Rearrange 
command to start the deletion process again. 


Step 4: Generate and update the book file 


This step generates all the files in the book file and repaginates the 
chapters throughout the book. If you did not delete any of the basic 
application chapters from the book file, go on to “Step 5: Define 
variables.” 

To update/generate a book file: 

1. Make sure the book file is open in FrameMaker. 

2. Choose File > Generate Book. 


3. In the Generate/Update Book dialog box, make sure that 
MasterTOC.fm and MasterIX.fm are displayed in the 
Generate list box. 


4. Click Update. 
5. The book file is updated and repaginated. 
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7. 


If error messages appear or the book file does not generate 
successfully, use the troubleshooting tips below to help you 
solve the problem. 


Regenerate the book file after correcting the problem. 


Troubleshooting tips for book files 
Try these tips to solve book file problems: 


If you’re working on various platforms, for example, on both 
a PC and a Macintosh, and the fonts differ from the original 
platform, you must open each file individually, accept the 
font substitution, and save the file. You cannot generate a 
book file successfully until you update or install the correct 
fonts on your system. 


Make sure all referenced files are in the correct location. An 
error message appears (“Can't Open filename.fm) and the 
book stops generating if the book file can’t find referenced 
files. Files can’t be found if you move them and they are not 
in the expected location. 


Resolve any unresolved cross-references. When unresolved 
cross-references are found while generating a book file, a 
message appears after the file is generated, indicating in 
which chapters they occurred. To solve the problem, open 
the chapter containing the unresolved cross-references, 
choose Edit > Find/Change, and choose Unresolved Cross- 
References from the Find pop-up menu. Find and resolve the 
cross references. 


Step 5: Define variables 


Variables are generic placeholders for specific information. In the 
End-User Documentation Kit, default values have been assigned to 
variables, which you will edit to customize them for use with your 
product. Note that all default variable definitions are displayed in 
red, which makes them easy to identify within the body of the 
document. 


In these examples, the variable name is in parentheses, followed by 
the definition: 
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Variable name Definition 
(Product Company Name) Palm 
(ProductName) Palm V 

(Product Type Short) handheld 

(Product Type Long) handheld computer 


To assign a definition to a variable: 
1. Open a chapter from your book file. 


Note that while you can open any chapter for this step, not all 
the chapters use all the variable definitions. For example, the 
front matter chapter, 00front.fm, uses only a few of the 
variables, so you may want to open a chapter that contains all 
or most variables, such as 01Intro.fm. 


2. Choose Special > Variable. 


3. The top portion of the Variable dialog box displays the list of 
default system variables, followed by Palm O8 book and 
poe variables. The Palm OS book and product variables 

egin at the “BookTitle” entry and are preceded by “<Red>” 
to indicate that the default variable is displayed within the 
documents in red. 


IMPORTANT: You must provide a definition for each Palm OS 
variable in the list, even if it is not used in every chapter. If you do 
not, you run the risk of displaying a generic variable definition in 
red within the body of the chapter. 


4. Select the first Palm OS variable in the list, “Book Title.” The 
default definition, <Red> (Book Title) appears below the list 
of variable names. 
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Variable Ea 


Variables: 


Variable name 
DesktopN ame 

DesktopN ameAdiective 

DesktopN ameLong 

DesktopN ameLongTM 


<Red>[BookTitle} 


Create Variable... | Edit Definition... | 
Convert to Text... | Update | 


[insert | Cancel | _Hep | 


5. Click Edit Definition. In the Definition field, enter your 
book’s title. 


In this example, the default book title is changed to “User 
Guide for the Paradise Organizer.” 


Default definition 


xl 
Name: [BookTitle 


er Taso |< Red>(Bookitle] 


x 
Name: [BookTitle 


PTT leah ser Guide for the Paradise Oraanize 


User Variables: Character Formats: 


<Default 4 Font> 
<Bald> 
<Computer Voice> 
<File Name> 


User Variables: Character Formats: 


<Default 4] Font> 
<Bold> 
< Computer Voice> 
<File Name> 
<Hypertext> 
<Italic> 

<Menu Command> 
<Note Warning> bg 


Add | Change | Delete | 
Cancel | 


<Note Warning> v 


Change | Delete | 
Cancel | 


6. Select the next variable in the User Variables section of the 
dialog box; then change the definition. Repeat this step until 
all the Palm OS variables are defined. 
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7. Click Done to exit the Edit User Variable dialog box. Click 
Done again to exit the Variable dialog box. 


IMPORTANT: Be sure to supply a definition for each variable in 
the list, even if you do not know if the variable is used within the 
chapters of your documentation. If you do not provide a definition, 
and the variable should appear within the chapter, the generic 
variable value is displayed in red within the chapter. 


8. Choose File > Save to save the book file. 


Be sure to save the book file whenever you make changes to 
it. 


Reference: Table of End-User Documentation 
Kit Variables 


For your reference, a table of all the variables, including Palm OS 
end-user documentation kit and default system variables, is 
provided below. Default system variables are followed by an (s). 


Variable Definition 
Book Title Book title 


DesktopFolderMacintosh Folder on the Macintosh containing device desktop 
software, for example, Palm 


DesktopName Device desktop software, for example, Palm Desktop 
software 


DesktopName Adjective Device desktop, for example, Palm Desktop 


DesktopNameLong Device Desktop device software, for example Palm 
Desktop device software 


DesktopNameLongTM __ Device desktop device software including a trademark 
symbol (™) for example Palm™ Desktop device software 


DesktopNameTM Device Desktop software including a trademark symbol 
(™), for example Desktop software 
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MailAppName 
Modem 


ModemTM 


Operating System 
Macintosh 


OperatingSystem 
OperatingSystem PC 
Product Description 
ProductCompanyName 
ProductCorp 
ProductName 
ProductNameGeneric 
ProductNameTM 
ProductOS 
ProductPrevious 


ProductTypeLong 


ProductTypeShort 
ProductTypeShortUpper 
WebCorpLong 
WebCorpShort 
WebProdNetLong 
WebProdNetShort 
WebProductLong 
WebProductShort 


Mail application name 


Device modem accessory, for example, Palm Modem 


accessory 


Device modem accessory with trademark symbol (™), for 
example, Palm Modem™ accessory 


Macintosh operating system 


Applicable operating system 


operating system PC 
Product description 


Product company name 


Product corporation (if necessary) 


Product name; for example, Palm V 


Product name generic, for example, organizer 


Product name with trademark, for example Palm V™ 


Product operating system 


previous version of product (not applicable if first release) 


product type, adjective and noun, for example, handheld 


computer 


Device type, lower case, for example, organizer 


Device type, upper case, for example, Organizer 


Web corp long, for example, http://www.name.com 


Web corp short, for example: name.com 


Web prod net long, for ex: http://www.name.net 


Web prod net short, for ex: name.net 


Web product long, for ex: http://www.devicename.com 


WebProductShort, if applicable, for example: device.com 
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Page Count (S) Displays the page number of the page on which the 
variable is displayed. 


Current Date (Long) (S) | Example: November 11, 1999 
Current Date (Short) (S) | Example: 11/8/99 


Modification Date (Long) Example: November 9, 1999 11:57 am 
(S) 


Modification Date Example: 11/8/99 
(Short) (S) 


Creation Date (Long) (S) Example: October 28, 1999 
Creation Date (Short) (S)_ Example: 10/28/99 


Filename (Long) (S) Example: C:\TechPubs\DocSet\EndUserkKit.fm 
Filename (Short) (S) Example: EndUserkit.fm 
Table Continuation (S) Ina multipage document, lets you display continuation 


text in the title or heading or footing rows. Use Table 
Continuation and Table Sheet for this purpose. 


Table Sheet (S) Ina multipage document, lets you display continuation 
text in the title or heading or footing rows. Use Table 
Continuation and Table Sheet for this purpose. 


Step 6: Import the variable definitions into all 
chapters 
Once you have defined the Palm OS variables in a single chapter 


file, you import them into all the remaining chapters in the book file 
(with the exception of the table of contents and the index). 


1. Make sure that the chapter containing the variable 
definitions is open in FrameMaker. (You can minimize the 
document if desired.) 


2. Opena chapter in which the variables have not been defined. 


3. From the open chapter with no variables defined, choose File 
> Import > Formats. 
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4. In the Import Formats dialog box, from the Import from 
Document menu, choose the document name that contains 
variable definitions. 


Import Formats Eg 
Import from Document: [Current 7] 


Current 


Import and Update: 


Tl Paragraph Format: T” Reference Pages 


I~ Character Formats IV Variable Definitions 

I Page Layouts I Cross-Reference Formats 
I~ Table Formats T Conditional Text Settings 
T~ Color Definitions I” Math Definitions 


I Document Properties 


While Updating, Remove: 
T” Manual Page Breaks [~ Other Format/Layout Overrides 


Cancel | Help | 


(No Undo) 


5. In the Import and Update area of the dialog box, make sure 
that the Variable Definitions option is selected. Deselect all 
the other options in the Import Formats dialog box. 


NOTE: If you later change other formats, such as Paragraph or 
Character formats, or the Page Layout definitions for a document, 
you can use other options in the Import Formats dialog box to 
update all the chapters in your documentation. 


6. Click Import to import the variable definitions. 
7. Repeat steps 2-6 for all remaining chapters. 


Step 7: Define cross-references 


By default, all the cross-references in the End-User Documentation 
Kit are disabled and are displayed in magenta. You can make a 
cross-reference active by selecting it, choosing Cross-Reference from 
the Special menu, and then redefining it. If you do not want to use a 
cross-reference, you can delete it from the chapter. 
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This guide assumes that you know how to define and insert cross- 
references using Adobe FrameMaker. If you don’t know how to 
create a cross reference, see your Adobe FrameMaker 5.5 
documentation or on-line help. 


Step 8: Update and generate the book file 


Once you have created your book file, identified which chapters you 
want to use, assigned variables and cross-references, and made any 
other desired modifications, update your book file to incorporate all 
the changes you’ve made. 


To update/generate your book file: 


Open your book file; then choose File > Generate / Update. If the 
book file does not generate properly, see "Troubleshooting tips for 
book files" on page xiv. 
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